Skip to content

test: verify firecracker fork-from-snapshot CoW isolation#214

Merged
sjmiller609 merged 1 commit into
mainfrom
hypeship/fork-shared-memfile
May 19, 2026
Merged

test: verify firecracker fork-from-snapshot CoW isolation#214
sjmiller609 merged 1 commit into
mainfrom
hypeship/fork-shared-memfile

Conversation

@sjmiller609
Copy link
Copy Markdown
Collaborator

@sjmiller609 sjmiller609 commented May 8, 2026 •
edited
Loading

Summary

Adds an integration test that documents and guards the CoW isolation properties of firecracker fork-from-snapshot. When a fork descends from a source's standby snapshot, the fork's mem-file must be a separate inode (reflink-cloned by forkvm.CopyGuestDirectory) so that mutating the fork — including taking a diff snapshot after divergence — never affects the source.

What the test does

TestFirecrackerForkFromSnapshot_DoesNotMutateSource (Linux-only, gated on /dev/kvm):

  1. Boot a firecracker source instance.
  2. Write a source-only sentinel into the guest.
  3. Standby the source — produces a full firecracker snapshot.
  4. Fingerprint the source's snapshot-latest/memory (inode + SHA-256).
  5. Fork the source. Assert the fork's mem-file inode ≠ source's; source's mem-file fingerprint unchanged.
  6. Restore the fork. Verify it sees the pre-fork sentinel.
  7. Write a fork-only sentinel; standby the fork — produces a diff snapshot on the fork's local mem-file.
  8. Re-fingerprint the source's mem-file. Must be byte-identical. Soft disk-usage check (gated on FICLONE probe): the fork lifecycle should consume substantially less than guest_mem on reflink-capable filesystems.
  9. Delete the fork. Re-fingerprint the source's mem-file — still byte-identical.
  10. Restore the source. Verify the pre-fork sentinel survived and the fork-only sentinel did not leak across.

The disk-usage assertion is gated on a runtime FICLONE probe; on ext4 and other non-reflink filesystems the copy falls back to sparse full-copy, so the "much-less-than-guest-mem" bound only holds on reflink-capable filesystems.

Test plan

  • CI runs TestFirecrackerForkFromSnapshot_DoesNotMutateSource on linux/amd64
  • Disk-usage assertion stays under the bound on reflink-capable CI filesystems (xfs/btrfs); skipped with log on ext4

This was referenced May 8, 2026
Closed
Draft
Draft
Draft
Draft
@sjmiller609
test: verify firecracker fork-from-snapshot CoW isolation
ac6bfde 
Adds TestFirecrackerForkFromSnapshot_DoesNotMutateSource. It puts a
firecracker source into Standby, forks it, restores the fork, writes a
divergent guest sentinel, then takes a diff snapshot of the fork.
Across the fork's full lifecycle (and after the fork is deleted) the
source's snapshot mem-file must keep the same inode and SHA-256, and
the source must still be restorable with its pre-fork guest state.

Includes a soft disk-usage check (gated on a FICLONE probe) that the
fork lifecycle consumes substantially less than a full guest-mem copy
on reflink-capable filesystems.

This documents the CoW isolation properties of reflink-based fork-from-
snapshot and guards against fan-out optimizations that would share an
inode with the source's snapshot mem-file.
@sjmiller609 sjmiller609 force-pushed the hypeship/fork-shared-memfile branch from d46be7a to 7b799f7 Compare May 13, 2026 18:13
@sjmiller609 sjmiller609 changed the title fork: share template mem-file via symlink for fan-out forks fork: share template mem-file via symlink for firecracker fan-out May 13, 2026
@sjmiller609 sjmiller609 changed the base branch from hypeship/templates to hypeship/template-as-state May 13, 2026 18:13
@sjmiller609 sjmiller609 force-pushed the hypeship/fork-shared-memfile branch 2 times, most recently from 355ad7f to a45d471 Compare May 13, 2026 20:39
@sjmiller609 sjmiller609 changed the title fork: share template mem-file via symlink for firecracker fan-out fork: share template mem-file via hardlink for firecracker fan-out May 14, 2026
Base automatically changed from hypeship/template-as-state to main May 14, 2026 15:58
@sjmiller609 sjmiller609 force-pushed the hypeship/fork-shared-memfile branch from a45d471 to 8b0000c Compare May 14, 2026 18:55
sjmiller609
sjmiller609 commented May 14, 2026
View reviewed changes
Comment thread lib/instances/fork.go Outdated
@sjmiller609 sjmiller609 marked this pull request as ready for review May 14, 2026 19:59
@firetiger-agent
Copy link
Copy Markdown

firetiger-agent Bot commented May 14, 2026

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: PR modifies fork/snapshot memory file handling in the instances library, not API endpoints (packages/api/cmd/api/) or Temporal workflows (packages/api/lib/temporal) as specified in the filter.

To monitor this PR anyway, reply with @firetiger monitor this.

@sjmiller609 sjmiller609 requested a review from hiroTamada May 14, 2026 21:07
hiroTamada
hiroTamada reviewed May 18, 2026
View reviewed changes
Comment thread lib/instances/fork.go Outdated
@sjmiller609 sjmiller609 marked this pull request as draft May 19, 2026 17:52
@sjmiller609 sjmiller609 force-pushed the hypeship/fork-shared-memfile branch from 101b5bd to 0f0137b Compare May 19, 2026 18:54
@sjmiller609 sjmiller609 changed the title fork: share template mem-file via hardlink for firecracker fan-out test: verify firecracker fork-from-snapshot CoW isolation May 19, 2026
@sjmiller609 sjmiller609 force-pushed the hypeship/fork-shared-memfile branch from 0f0137b to ac6bfde Compare May 19, 2026 19:43
@sjmiller609 sjmiller609 requested a review from hiroTamada May 19, 2026 20:25
@sjmiller609 sjmiller609 marked this pull request as ready for review May 19, 2026 20:25
@firetiger-agent
Copy link
Copy Markdown

firetiger-agent Bot commented May 19, 2026

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

Any PR that changes the kernel API. Monitor changes to API endpoints (packages/api/cmd/api/) and Temporal workflows (packages/api/lib/temporal) in the kernel repo

Reason: This PR adds an integration test for firecracker fork-from-snapshot behavior and does not modify kernel API endpoints (packages/api/cmd/api/) or Temporal workflows (packages/api/lib/temporal).

To monitor this PR anyway, reply with @firetiger monitor this.

@sjmiller609 sjmiller609 merged commit 1b7d0b7 into main May 19, 2026
12 of 13 checks passed
@sjmiller609 sjmiller609 deleted the hypeship/fork-shared-memfile branch May 19, 2026 20:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hiroTamada hiroTamada hiroTamada approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@sjmiller609 @hiroTamada